OPLLINT USER GUIDE ADVANCED CHECKING UTILITY FOR OPL PROGRAMS Version 2.20 Copyright PSION UK plc 1990,1991,1992. The information contained within this document is the property of PSION UK PLC and may not be copied or disclosed in whole or part, except with the prior permission of PSION UK PLC. PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Psion endeavours to ensure that the information in this document is correct, but does not accept liability for any omissions or errors. Specifications and statements as to performance in the document are estimates only, provided for guidance. Statements in the document are not part of a contract or product licence insofar as they are incorporated into a contract or licence by express reference. Issue of this document does not entitle the recipient to access or use of the products described, such access or use being subject to separate contracts or licences. OPLLINT User Guide Issue: V1.20 Date: 15th September 1992 Copyright PSION UK plc 1990,1991,1992. Trademarks Psion and the Psion logo are registered trademarks. Psion Mobile Computer, Psion MC, Psion Organiser II, Datapak and Rampak are trademarks of PSION plc. IBM PC, IBM XT and IBM AT are trademarks of International Business Machines Corp. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 ii PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- CONTENTS 1 INTRODUCTION 1 1.1 WHAT IS A LINT? 1 1.2 WHY DOES OPL NEED A LINT? 1 2 WHAT OPLLINT CHECKS FOR 2 2.1 TYPES OF OPL 2 2.2 CHECKS ON VARIABLES 2 2.3 FILE RECORD FIELDS 3 2.4 PROCEDURE CALL CHECKS 3 2.5 REDUNDANCY CHECKS 4 2.6 PROGRAM EFFICIENCY 4 3 INSTALLING OPLLINT 5 4 USING OPLLINT 6 4.1 INVOKING OPLLINT 6 4.2 GETTING THE HELP SCREEN 6 4.3 INPUT FILES, -i FLAG 6 4.3.1 Using An OLL Input File 7 4.3.2 Using A BLDPACK Input File 7 4.3.3 Using An MC-OPL, OPL/g or OPL/w Module 8 4.4 SELECTING OPL OR PPO FILES: -f FLAG 8 4.5 SETTING OPL PATHS: -d FLAG 8 4.6 HOW OPLLINT PROCESSES FILES 8 4.7 PRODUCE OUTPUT BLD FILES: -b FLAG 9 4.8 SET A NEW ODB THRESHOLD: -T FLAG 9 4.9 INCLUDE A LANG EXTENSION FILE: -l FLAG 10 4.10 SET A LANG EXTENSION PATH: -s FLAG 10 4.11 DISABLE/ENABLE WARNINGS: -w FLAG 10 4.12 SPECIFY A START POINT: -r FLAG 11 4.13 PRODUCE A POPULARITY LIST: -p FLAG 11 4.14 RIGOUROUS GLOBAL CHECKS: -g FLAG 11 4.15 SPECIFY THE TARGET MACHINE: -t FLAG 12 4.15.1 Specific Target Machines 12 4.15.2 Finding Compatible Machines 12 4.15.3 Number Conflict When Using The -t? Flag 13 4.16 CALLING STRUCTURE FLAGS: -c AND -o 13 4.17 PREPROCESSOR FLAGS: -D, -I, -U 14 4.18 SOME EXAMPLE COMMAND LINES 14 4.19 THE OL ENVIRONMENT VARIABLE 14 4.20 OPLLINT FLAG SUMMARY 15 5 ERRORS AND WARNINGS 17 5.1 ERROR MESSAGES 17 5.2 WARNINGS 25 5.3 EXIT CODES 27 6 LANGUAGE EXTENSION FILES 28 6.1 STANDARD FILES 28 6.2 MAKING YOUR OWN LANGUAGE EXTENSION FILES 29 ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 iii PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 7 ORDERING PROCEDURES 30 8 CUSTOMISING OPLLINT 31 9 THE PREPROCESSOR 32 10 FEATURES NEW TO V2.00 33 10.1 CHANGES FROM V1.12 TO V2.00 33 10.2 FEATURES ADDED TO OPLLINT V2.00 33 10.3 FEATURES ADDED TO OPLLINT V2.10 33 10.4 FEATURES ADDED TO OPLLINT V2.20 33 ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 iv PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 1 INTRODUCTION 1.1 WHAT IS A LINT? LINT was a program written to run on UNIX systems. It was developed to help debug programs written in C. LINT read through the sources for a program and performed a whole set of checks on the code, reporting potential errors. 1.2 WHY DOES OPL NEED A LINT? When an OPL procedure is translated error checking is performed only on that procedure. For instance when a variable name is encountered: if it is not defined as a local variable then it is assumed to be a global variable. The variable may simply not exist or be spelt wrong. Such an error will only be found at run time with an UNDEFINED EXTERNAL message. Similar errors can occur with procedure calls. The only way of fully testing the code is by carrying out an exhaustive test of every line of code in the program. Where there are several errors in different procedures it may take several translate-build cycles to complete the testing. These problems are all syntax errors that can be detected before the program is run on the target machine. OPLLINT carries out a variety of checks on an entire OPL system. It provides early detection of errors and significantly reduces program debugging and test time. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 1 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 2 WHAT OPLLINT CHECKS FOR 2.1 TYPES OF OPL Psion produces two type of machines: þ The Organiser II. Several models are available including the XP, CM, LZ and LZ64. þ SIBO machines. SIBO is a generic name for Psion machines that run the Psion EPOC operating system. The following machines are all SIBO machines: MC200, MC400, HC100, HC110, HC120 and the Series 3. There are currently 5 variants of the OPL language: þ XP-OPL running on Organiser IIs (Model XP and compatibles). þ LZ-OPL running on Organiser IIs (Model LZ and compatibles). Contains some enhancements to XP-OPL. þ MC-OPL running on older SIBO machines (MC200 and MC400). Contains many enhancements over LZ-OPL. þ OPL/g running on recent SIBO machines (MC200, MC400, HC100, HC110, HC120). OPL/g includes all MC-OPL enhancements plus commands to draw graphics. þ OPL/w running currently only on the Series 3. OPL/w includes all OPL/g enhancements plus new WIMP commands. OPLLINT will work with all these type of OPL. In addition it will warn you if you are using a variable name that is a keyword in another type of OPL (thus allowing you to produce portable OPL). OPLLINT will also determine what types of OPL a program is compatible with. 2.2 CHECKS ON VARIABLES OPL has dynamic scope. There may be many variables in a program. Not all these variables can be accessed at once. The variables that the program can actually access at any given point are said to be "in scope" at that point. Thus if a variable is in scope the program can reference it. If the variable is not in scope the program will not be allowed to reference it. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 2 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- In an OPL procedure you can define variables as LOCAL or GLOBAL. While you are inside a procedure all the variables you defined in it are available to you: they are in scope. When you return from the procedure all of these variables will be discarded: they will all go out of scope. The difference between LOCAL and GLOBAL variables occurs when a second procedure is called from inside the first one. LOCAL variables defined in the first procedure are not available in the second. However, the GLOBAL variables defined in the first procedure ARE in scope in the second procedure. The same applies for a third procedure called from the second. This means that the variables in scope in a function depend on where the function was called from. All the variables defined as GLOBAL in the functions that lead to this function being called are in scope. This is how dynamic scope is defined. OPLLINT will check that all variables used exist as either local variables or global variables that are in scope. OPLLINT will also check that a global is not in scope more than once. This would happen if for instance a global was declared with the same name in two procedures. If one procedure called the other there would be two globals of the same name in scope. Whilst this is legal OPL code, it is bad programming practice and could lead to obscure bugs that are difficult to detect. 2.3 FILE RECORD FIELDS In OPL file records are treated as a set of variables with a prefix (a,b,c or d and a dot): one variable for each field. These present a problem because the variables available depend on the file currently open. OPLLINT has no way of telling which file will be open at a given point in the program and can perform no checking on these variables. OPLLINT therefore ignores them. 2.4 PROCEDURE CALL CHECKS OPLLINT checks that when a procedure is used it is called with the correct number of arguments and that each argument is of the correct type. A type in OPL is either an integer, a floating point number or a string. For MC-OPL, OPL/g and OPL/w a type can also be a long integer. OPLLINT will not check calls to built in OPL functions since OPLTRAN (or TRAN for the MC/HC) will report these errors. All the code given to OPLLINT must have been successfully translated. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 3 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- When a procedure call is found the language extensions are checked first, followed by the OPL procedures defined in the system. The type and number of arguments to an OPL procedure must match exactly the arguments listed when the procedure is defined. Language extensions are more flexible. They can have a variable numbers of arguments and arguments of no fixed type. Up to 16 files listing language extensions can be included. See chapter 6 for more information on how to make these files. Language extensions are used to define the arguments expected by machine code procedures for XP-OPL and LZ-OPL and library procedures for OPL on SIBO machines. Note that if you use the "call procedure by name" feature (the @ operator in OPL/g and OPL/w) OPLLINT will not perform any checking on the procedure call since it will not know which procedure is being called. 2.5 REDUNDANCY CHECKS OPLLINT will warn you if any variables or procedures have been declared and never used. Although they do no harm they are a waste of memory. 2.6 PROGRAM EFFICIENCY On the Organiser II procedures at the top of a datapak are found and loaded much faster than those lower down the datapak. OPLLINT keeps a count of the number of times a procedure is called. This gives an indication of how widely used a procedure is. This information can be used by OPLLINT to order the position of procedures on a pack. The program can produce output .BLD files that can be used by BLDPACK to build the program pack ordered in this way (for Organisers only). See chapter 7 for more information about ordering procedures. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 4 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 3 INSTALLING OPLLINT The disk supplied contains the OPLLINT program plus some language extension files. To copy the program onto your system follow these instructions: Put the disk into drive A and type: MD c:\opllint XCOPY a:*.* c:\opllint /s /e OPLLINT is now installed into a directory on your hard disk called c:\opllint. If you wish to use another drive or directory name you will need to change the supplied batch files that run OPLLINT for you. The two batch files that run OPLLINT are called OL.BAT and OLR.BAT. In order for the system to work the c:\opllint directory has to be put into the system path. To do this modify your AUTOEXEC.BAT file. This is the file that starts up your computer. Somewhere in this file there will be a PATH command that sets the paths the computer searches when you type a command. You will need to add c:\opllint to this path. For instance a path that searches the c:\dos directory as well as the opllint directory will look like this: PATH=c:\dos;c:\opllint; Once you have changed AUTOEXEC.BAT and rebooted your system you will be able to run OPLLINT from anywhere on your system by typing OL or OLR. For more information on the PATH command and writing AUTOEXEC.BAT files see you MS-DOS manual. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 5 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4 USING OPLLINT 4.1 INVOKING OPLLINT OPLLINT is started by typing OL at the MS-DOS prompt followed by some filenames and flags. These filenames and flags are covered in the next few sections. This is the syntax for the command line: OL infile [infile1] [flags] OPLLINT can produce a lot of errors. Sometimes it is more convenient to put these in a file that you can refer to or print out. For this reason we have provided a second command called OLR. Use it in just the same way as OL: the only difference is that all the output from OPLLINT will be put into a file called ERR.OUT which you can then inspect. OL and OLR are in fact batch files that run the main OPLLINT program. These batch files can be customised to your own requirements. For more information see chapter 8. 4.2 GETTING THE HELP SCREEN If you type OL with no filenames or you include a ? or a -? on the command line you will get a help screen. It gives you a summary of the flags used by OPLLINT and what they do. The examples bellow will all produce a help screen: OL OL ? OL -? 4.3 INPUT FILES, -i FLAG In order to work OPLLINT needs a complete list of OPL files used by your OPL system. You can give OPLLINT one or two input filenames on the command line that give this list of OPL files. Three different types of input file can be used by OPLLINT. To show which type of file you are using you must use the -i flags shown below on the command line. If you do not add an extension to the filename you give, the appropriate one (shown in brackets below) will be automatically added for you. -ioll OPLLINT list file (.OLL) ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 6 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- -ibld BLDPACK format file (.BLD) -imc MC-OPL, OPL/g or OPL/w Module (.OPL or .PPO : see -f flag) NOTE: all input files used by OPLLINT are preprocessed: even the BLD and OLL files. See section 9 for more details. 4.3.1 Using An OLL Input File The simplest option is the OPLLINT list file. This is the default input file type. The file is just a list of the filenames (one per line). The path given for each file is the one that is used to access the file. Data files and binary files can be included in this list - they are not processed by OPLLINT but are included in the output BLDPACK file if one is selected (see -b flag below). Filenames given in this file may contain the standard wildcards * and ?. Thus to include all the OPL files in a directory called c:\source you would add this line to the OLL input file: c:\source\*.OPL Command line options can also be given in the OLL file by using the special directive OL: followed by a list of command line flags. It is therefore possible to put all the flags you normally type in on the command line into the OLL file. For example: OL: -rstart -lcomslink -p+ Since the OLL if the default input file it is possible to put all the command line flags you need into the OLL file. Then to run OPLLINT you just need to type OL followed by the name of the OLL file: ol test 4.3.2 Using A BLDPACK Input File The BLDPACK file is slightly more complicated since the BLDPACK file actually lists OB3 files. OPLLINT assumes that files with an OB3 extension refer to an OPL (or PPO see -f flag) file. OPLLINT will search for this OPL/PPO file using first the path given in the BLDPACK file, and then the set of paths given with the -d flag (see below). Files with other extensions are not processed, but the filenames are used to produce the output BLDPACK files (see -b flag below). ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 7 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4.3.3 Using An MC-OPL, OPL/g or OPL/w Module The third input file type applies only to OPL running on SIBO machines: MC-OPL, OPL/g or OPL/w. The name of the top module of the program is given. These modules contain commands that load in other modules (the LOADM command). OPLLINT can look for these commands and build up its own list of files to use. For this system to work the filename must be included in quotes after the LOADM command (if the filename is in a string OPLLINT will not be able to extract it). Every module included this way will also be searched for LOADM commands and these files will also be loaded. Duplicated filenames are ignored. The path given is stripped of the filename and the paths given with the -d flag (see below) are used to find the file. If no extension is given the extension .OPL or .PPO is added (depending on the -f flag - see below). Note that OPLLINT will given no error if the source file could not be found. 4.4 SELECTING OPL OR PPO FILES: -f FLAG The -f flag simply selects the default extension added to OPL files when no extension is given. The default is to use the extension OPL (-fopl flag). To use the PPO extension instead put the -fppo flag on the command line. 4.5 SETTING OPL PATHS: -d FLAG The -d flag is used to specify a path for OPLLINT to find OPL or PPO files. Up to 8 of these paths can be specified. For instance to use the paths c:\test\src1 and c:\test\src2 you would add to the command line: -dc:\test\src1 -dc:\test\src2 4.6 HOW OPLLINT PROCESSES FILES Having obtained a list of OPL or PPO files OPLLINT will read through the files in two passes and then check the scope of variables in the system. OPLLINT does not repeat checks made by OPLTRAN (or TRAN for the MC/HC). It is assumed that all the OPL files have been successfully translated. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 8 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- OPLLINT works in several stages. If errors occurred in the previous stage the program will not continue. OPLLINT will report if it completed successfully or if there were too many errors for it to complete all its tests. 4.7 PRODUCE OUTPUT BLD FILES: -b FLAG This flag has no meaning for code running on SIBO machines. The -b flag is used to produce output BLDPACK (.BLD) files with the OPL procedures in the most efficient order. The same number of input and output files are needed. Following the -b is the filename of the output file. The extension .BLD will be automatically added if one is not given. To produce the output file OUT.BLD you would include this on the command line: -bout If you are using two input files, you need two output files. The second output file is given in the same way as the first. For example to produce output files called ONE.BLD and TWO.BLD you would use: -bone -btwo The order of the OB3 files is determined by the number of calls made to each procedure. BIN files are put at the top of the file. All other files are assumed to be ODB or data files. These files will be placed above all procedures that have less than 10 calls. This value of 10 is a default and can be changed with the -T flag (see below). See chapter 7 for more information on the ordering of procedures on a pack. 4.8 SET A NEW ODB THRESHOLD: -T FLAG This flag allows the default threshold value of 10 for ODB files to be replaced with the value given after the -T flag. This value determines the position of ODB files in the output BLD files if the -b flag is used. The ODB files are placed above all the procedures that have less than this popularity value. To set the threshold value to 23 you would use: -T23 All the procedures that were only called 23 or less times would be placed below the ODB files in the output files produced by the -b flag. See chapter 7 for more information. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 9 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4.9 INCLUDE A LANG EXTENSION FILE: -l FLAG Language extensions can be used to define calls to procedures to which you have no source code (for instance a set of library procedures provided by a third party). Language extensions are also used on Organisers to add special features to OPL. OPLLINT needs to know what arguments these extensions expect so that it can check calls made to them. The -l flag must be followed by a filename. The extension .LEX will be automatically be added to this name. The current directory will be searched first. If the file was not found the standard directories (set with the -s flag) will then be searched. The LEX file should contain a list of procedures with the arguments these procedures expect defined in full. OPLLINT uses the data in this file to check the arguments given to language extensions. For more information see chapter 6. Up to 16 language extension files can be included in this way. For example to include the language extension files comslink and myexts you would use: -lcomslink -lmyexts 4.10 SET A LANG EXTENSION PATH: -s FLAG The -s flag must be followed by a path (not ending in a backslash). This path is used to find language extension files not found in the current directory (see above). There are several standard language extension files provided with OPLLINT for various devices like the CommsLink on the Organiser as well as the definitions of the library procedures used on SIBO machines. All these files can be put in one directory and the -s flag can be used to tell OPLLINT where this directory is. This example would set the standard directory to c:\std\langexts : -sc:\std\langexts The batch files that runs OPLLINT, OL.BAT and OLR.BAT, actually use this flag to set the standard directory, so you should only need to use it if you are customising the system. 4.11 DISABLE/ENABLE WARNINGS: -w FLAG The -w flag disables or enables warning messages. It is advised that warnings are left enabled since they can provide a lot of useful information about potential problems with an OPL program (they are on by default). ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 10 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- To disable warnings include this flag on the command line: -w- To enable them include this flag: -w+ or -w 4.12 SPECIFY A START POINT: -r FLAG The -r flag is followed by the name of a procedure. This procedure name is used as a start point for the program. The start points are needed for OPLLINT to be able to work through the calling structure of the OPL program when it is checking that globals are in scope. OPLLINT requires at least one start point to be specified. You may give up to 8 start points. For example to give boot and debug as start points you would use: -rboot -rdebug 4.13 PRODUCE A POPULARITY LIST: -p FLAG The flag -p+ (or -p) will produce an output file of the same name as the input file but with the extension .POP. The list will show the number of times each procedure is called and will be sorted into order with the most popular procedure first. The flag -p- disables the production of this list (the default). 4.14 RIGOUROUS GLOBAL CHECKS: -g FLAG When this flag is set to -g- (the default) globals of the same name can be defined in several procedures. This allows for procedures that need to return several variables to do so using globals. If this flag is set to -g+ (or -g) on the command line a more rigourous approach is taken: globals can only be declared once. Globals with duplicated names will be flagged as errors. This would remove the possibility of mixing up which global was being used. When this scheme is used the globals are often all defined in the topmost procedure. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 11 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4.15 SPECIFY THE TARGET MACHINE: -t FLAG 4.15.1 Specific Target Machines OPL works on several different machines. The keywords and syntax for each machine differ slightly. You can use the -t flag to specify which of the machines you wish it to run on: -txp Organiser XP or CM -tlz Organiser LZ or LZ64 -tmc Mobile Computer with standard OPL -tmcg Mobile Computer with graphics (OPL/g) -tmcw Mobile Computer with WIMP (OPL/w) OPLLINT will warn you of you are using a variable name which is a keyword on another type of machine. 4.15.2 Finding Compatible Machines If you specify the flag -t? (which is the default) OPLLINT will work out which versions of OPL your code is compatible with. Note that you cannot use variable names that are keywords in any of the OPL versions if you use this flag. For this test OPLLINT is only looking at the syntax and keywords you are using in your program. This feature is provided to give you an idea of how portable the OPL itself is. It does not guarantee that the program will run on all the machines it specifies, but that the OPL used is consistent with the version of OPL used on that particular machine. For instance to port a program from an Organiser to a SIBO machine will require putting all the OPL procedures in a few module files and adding the PROC and ENDP keywords round each procedure as well as allowing for different filing systems and displays. Even though the OPL may be compatible with both machines it is unlikely to work without modification. The keywords PROC, ENDP, LOADM and UNLOADM are considered intrinsic to SIBO OPL modules and are ignored for these tests. They would have to be removed anyway if the system was ported to an Organiser version of OPL that does not use these keywords. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 12 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4.15.3 Number Conflict When Using The -t? Flag When using the -t? flag OPLLINT converts all literal numbers given in the program to types used by the Mobile Computer OPL. Numbers that are bigger than the integer limit and smaller than the long integer limit are taken to be long integers. The OPL used by Organisers however does not support long integers, so a conflict can occur. Here is an example: test:(32768) The number given is just bigger than the limit for an integer, so OPLLINT regards this as a long integer. If the procedure test was expecting a floating point value an error would be produced since a long value cannot be passed to a floating point argument. To resolve this problem put a .0 on the end of the number: the number is then forced to a floating point value. test:(32768.0) This problem does not occur when using the -txp or -tlz flags since OPLLINT will only convert numbers to long integers if the Mobile Computer OPL is being used. 4.16 CALLING STRUCTURE FLAGS: -c AND -o OPLLINT will produce a printout of the calling structure used by the OPL program. To produce the calling structure include the flags -o or -o+ on the command line. To disable the calling structure output put the flag -o- on the command line. Since the calling structure can be nested up to many levels the output is split up into several output files. These output files can then be printed out and joined together to given the complete structure. The output files produced by OPLLINT use the name of the first input file given on the command line. The output files are given the extensions .P00 to .P15. Thus OPLLINT might produce, for a fairly complex program, two output files called TEST.P00 and TEST.P01. The output files are split up according to the size of your printer. The default size is 80 columns. If you have a wide carriage printer or are printing in condensed mode you can set the column width with the -c flag. For instance to set the width to 132 columns you would use: -c132 ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 13 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 4.17 PREPROCESSOR FLAGS: -D, -I, -U The -D flag defines a manifest constant. If an equal sign follows the constant name then the text after the equal sign is used as the constants definition. If no text is given the constant is defined to be 1. Up to 16 -D flags can be put on the command line. Here are some examples: -DVERSION=V1.00 -DDEBUG The -U flag undefines a previously defined constant. Up to 16 -U flags can be put on the command line. For example: -UDEBUG -UVERSION The -I flag sets the paths where the preprocessor looks for include files. Up to 16 of these paths may be given on the command line. For example: -Ic:\test\include -Ic:\std\include These defines, undefines and include paths are used for every preprocessed file OPLLINT reads, including the BLD, OLL and language extension files. See section 9 for more details. The manifest constant _OPLLINT is defined by OPLLINT each time it runs. This provides a way of inserting OPLLINT specific code into a program. 4.18 SOME EXAMPLE COMMAND LINES ol test -ioll -lext1 -lext2 -rboot This command line tells OPLLINT to read the file TEST.OLL. Language extension file EXT1.LEX and EXT2.LEX are read in and the procedure boot is used as a starting point. ol test test1 -ibld -bout -bout1 -lcomslink -rboot This command line uses TEST.BLD and TEST1.BLD as input files. Output files OUT.BLD and OUT1.BLD are produced. The language extension file COMSLINK.LEX will be read in from the standard directory (set by OL.BAT) assuming there is no COMSLINK.LEX in the current directory. The starting procedure is boot. 4.19 THE OL ENVIRONMENT VARIABLE OPLLINT also reads an environment variable called OL. This variable is set with the MS-DOS command SET. It can contain any flag or filename that you would put on the command line. See your MS-DOS manual for more information on the SET command and environment variables. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 14 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Note that OPLLINT uses the last value of a flag it is given. The OL variable is read first, followed by the command line, followed by the command line in the OLL file (if one is being used). If you put a -p- in the OL variable, then putting a -p+ on the command line would override it. 4.20 OPLLINT FLAG SUMMARY The following flags are accepted by OPLLINT: ? or -? Produce a help screen -bout Produce a .BLD output file (Max 2) -cnn Set width of printer to nn columns -dpath Set a path for OPL sources (Max 16) -Dname Define a preprocessor manifest constant (Max 16) -fopl Use OPL as default extension -fppo Use PPO as default extension -g+ or -g Enable rigourous global checks -g- Disable rigourous global checks -ibld Use BLDPACK format input file -ioll Use OPLLINT list file format input file -imc Use an MC-OPL, OPL/g or OPL/w module and find other module names -Ipath Add an include path for the preprocessor to find include files (Max 16) -lfile Include language extension file (Max 16) -o+ or -o Produce calling structure of OPL system. -o- Produce no calling structure -p+ or -p Produce popularity lists -p- Produce no popularity lists -rname Set starting procedure (Max 8) -spath Set path for language extensions (Max 16) ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 15 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- -t? Find machines compatible with the OPL used in this system -tlz Target is an Organiser LZ or LZ64 -tmc Target is a Mobile Computer (MC-OPL) -tmcg Target is a Mobile Computer (with graphics: OPL/g) -tmcw Target is a Mobile Computer (with WIMP: OPL/w) -txp Target is an Organiser XP or CM -Tnn Set new ODB threshold level -Uname Undefine a preprocessor manifest constant (Max 16) -w+ or -w Enable warnings -w- Disable warnings ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 16 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 5 ERRORS AND WARNINGS OPLLINT produces several error and warning messages. Each message is explained below. 5.1 ERROR MESSAGES All error message lines have this format: Error FFFF LL: message where FFFF is the name of the file and LL the line number where the error occurred. Only the error message is given below. Error messages produced by the preprocessor are not repeated here. For details of these messages see the TRAN user guide. A maximum of xx 'xxxx' flags may be given Too many flags of this type have been put on the command line, the OL environment variable or in an OLL file. Argument NN in call to RRRR wrong type Argument number NN in the call to procedure RRRR was the wrong type. Argument too long An argument given on the command line (or in the OL environment variable or OLL file) is too long. Character expected after % sign A character is required after the % sign to give an ASCII value. Check OPL files have been successfully translated. Could not convert number following 'xxxx' flag The number following this flag could not be converted successfully. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 17 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Could not find name of language extension Invalid name given in language extension definition. Could not open file FFFF The file FFFF could not be opened. Different number of input and output files The number of output files given with the -b flag must be the same as the number of input files. Duplicated global VVVV The global VVVV has been declared more that once. This error will only be produced if the -g flag is enabled. Expected + or - sign after 'xxxx' flag This type of flag requires a + or - sign after it to switch the option on or off respectively. Global VVVV defined as both an array and a non-array The global given has been declared as an array in one place and a normal variable in another. This is legal in OPL but means that OPLLINT can not check if the variable is being used as an array or a normal variable. Thus OPLLINT will not allow globals of the same name to be declared as arrays and normal variables. Global VVVV does not exist This global VVVV has never been declared within the system. Global VVVV in scope more than once (called by RRRR line LL) The global VVVV is in scope more than once: i.e. more than one procedure has declared this as a global before returning. This procedure was called by the procedure RRRR at line LL. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 18 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Global VVVV not in scope (called by RRRR line LL) The global VVVV is not in scope at this point of the program. This procedure was called by the procedure RRRR at line LL. Global VVVV not in scope (this is a starting procedure) The global VVVV is not in scope. This procedure is a starting procedure and so was never called by another procedure first. Identifier 'xxxx' too long This variable or procedure name has too many characters. Insufficient memory to continue There is not enough memory to allow the program to run. If there are any memory resident programs installed on your machine remove them and try again. Invalid hexadecimal number 'xxxx' given The number given is not a valid hexadecimal number. Invalid number 'xxxx' given The number given is not a valid decimal number. Invalid number of columns given: nn The number given after a -c flag is not a valid number of columns for a printer. Invalid ODB file threshold of xx given An invalid number was given as a threshold with the -T flag. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 19 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Invalid procedure argument 'xxxx' given An invalid argument has been given for this procedure. Invalid procedure name 'RRRR' given An invalid procedure name has been given. Invalid variable name 'VVVV' given An invalid variable name has been given. Language extension RRRR redeclared with different arguments The language extension RRRR has been declared more than once, with a different set of arguments. Line too complex to parse The line given is too complicated for OPLLINT to understand. Local variable VVVV redeclared The local name given has been used more than once. It is legal in OPL to use the same name for an array and a normal variable. This is however bad practice and OPLLINT will treat it as an error. This allows OPLLINT to check that variables declared as arrays are always used as arrays. Mismatched ')' in line Closing bracket has been given without corresponding opening bracket. Mismatched PROC and ENDP statements A PROC or ENDP statement is missing. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 20 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Missing " in line The ending quote mark (") surrounding a literal string is missing from this line. Missing ENDV statement An ENDV command has been found without a matching VECTOR command. No ENDP found before end of file The end of a file has been reached before an ENDP statement was found. No extension given for file 'FFFF' The filename given did not have an extension. In the OLL input file all filenames must have an extension. No start point given: use -r flag At least one starting point must be specified with the -r flag before OPLLINT can commence. No text given after 'xxxx' flag The command line flag shown requires a text string after it. Procedure RRRR does not exist The procedure RRRR has never been declared within the system. You many have forgotten to include the file in the input BLD file. Procedure RRRR redeclared The procedure RRRR has been declared more than once. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 21 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Starting procedure RRRR not found The starting procedure RRRR given with the -r flag was not declared in the system. String and numeric types mixed String and numeric types found in an expression. Check OPL files have been successfully translated. Syntax error in declaration of variable VVVV An invalid variable name has been given in a GLOBAL or LOCAL declaration. Check OPL files have been successfully translated. Syntax error in language extension definition There is a syntax error in the definition of a language extension. Syntax error in procedure call from string An error was found in a function call from a string using the @ command. Syntax error in procedure definition There is a syntax error in the definition of a procedure. Check OPL files have been successfully translated. Syntax error in variable declaration list GLOBAL or LOCAL declaration is invalid. Check OPL files have been successfully translated. Text following 'xxxx' flag is too long The text given after the command line flag shown was too long. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 22 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Too many arguments given Too many filenames were specified on the command line (or in the OL environment variable or OLL file). Too many arguments in language extension definition Too many arguments were given in the definition of a language extension. Unexpected character 'xx' in line An invalid character was found whilst reading a line. Check OPL code has been successfully translated. Unexpected characters after 'xxxx' flag Invalid characters followed the flag given on the command line (or in the OL environment variable or OLL file). Unexpected separator ':' in line A colon was found in an invalid position whilst reading a line. Check OPL code has been successfully translated. Unknown flag 'xxxx' This flag given on the command line (or in the OL environment variable or OLL file) is not recognised by OPLLINT. Variable VVVV was declared as an array You have used a variable that was declared as an array as if it were a normal variable. Variable VVVV was not declared as an array You have used a normal variable as if it were an array variable. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 23 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Wrong number of arguments in call to RRRR The wrong number of arguments were used in a call to procedure RRRR. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 24 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 5.2 WARNINGS All warning lines have this format Warning FFFF LL: message where FFFF is the name of the file and LL the line number where the warning occurred. Only the warning message is given below. VVVV is a keyword in other OPL versions The variable name VVVV is used as a keyword in a different OPL version on another machine. This just warns you that your OPL code is not portable if you use this variable name. Global VVVV declared in procedure RRRR but never used This global VVVV is declared in procedure RRRR but never used. Local VVVV has same name as a global This local VVVV has the same name as a global variable. This is bad programming practice and should be avoided since it is easy to confuse the two variables. Local VVVV has same name as a global array This local VVVV has the same name as a global array variable. Moreover the global is declared as an array whilst the local is not. Although it is legal in OPL to have a array and a non-array with the same name, it is bad programming practice. Local VVVV has same name as a global non-array This local VVVV has the same name as a global variable. Moreover the local is declared as an array whilst the global is not. Although it is legal in OPL to have a array and a non-array with the same name, it is bad programming practice. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 25 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- Local VVVV never used in procedure RRRR The local VVVV is declared in procedure RRRR but never used. Parameter VVVV never used in procedure RRRR This formal parameter is declared but never used. Procedure RRRR declared but never called This procedure RRRR is declared but never called anywhere within the system. Procedure RRRR declared but never reached The procedure has been declared and calls have been made to it from within the code, yet these calls are never actually reached when the system is run. Procedure name RRRR is different from file name This file contains a procedure which has a different name to that of the file. This is not an error, but usually the filenames and procedure names match. OPLLINT uses the procedure name to identify a procedure. If the procedure name and the filename are different it can be confusing. This message will warn you if the names do not match up. Procedure RRRR has been renamed to RRRR with a BLDPACK alias The alias field in the a BLDPACK file has been used to rename a procedure. The alias name is now used in all references to the procedure. This message is just to warn that this change has occurred since it can only be seen by looking at the input BLD file. Unknown preprocessor command 'xxxx' The preprocessor command given is not recognised by the system and has been ignored. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 26 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 5.3 EXIT CODES Exit codes can be used by other programs to see if OPLLINT completed successfully or not. The following codes are set: 0 Program completed successfully OR only warnings occurred. 2 Errors occurred. The environment pseudo-variable ERRORLEVEL will be given one of these values upon the termination of OPLLINT. See your MS- DOS manual for more information about ERRORLEVEL and how to use it. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 27 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 6 LANGUAGE EXTENSION FILES 6.1 STANDARD FILES There are several language extension files supplied with OPLLINT that define the language extensions used in standard PSION products. These files are all kept in the c:\opllint\langexts directory. If you use the OL batch file it will automatically set the standard directory to this directory for you. To use any of these files you simply use the -l flag when you run OPLLINT. For instance to use the comslink file you would add the following to your command line: -lcomslink The following files are supplied: LIBRARY Definitions for all the procedures used in the SIBO OPL library. COMSLINK Standard Organiser ComsLink language extensions. BARCODE For Organiser bar code readers. PARALLEL Organiser parallel printer interface. MAGSWIPE Organiser magnetic card swipe. PRINTER Organiser Printer extensions. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 28 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 6.2 MAKING YOUR OWN LANGUAGE EXTENSION FILES OPLLINT reads in language extension definitions from language extension files. These files have the extension .LEX. They contain a list of procedures with the arguments that they expect. These files are preprocessed. See section 9 for more details. The types of the arguments are important. A type in OPL can be an integer, a long (for SIBO machines), a floating point number or a string. OPLLINT will check that all calls made to this extension use the correct type for each argument. For example to define the language extension XTSEND the file would contain a line like this: XTSEND:(remote$,local$,type%) The names of the variables used to give the arguments are not important: they are just used to determine the type of each argument, but they must not be keywords. Thus if the variable name does not end in a %, &, or $ sign it is taken to be a floating point value. In addition to the standard OPL data types the asterisk (*) symbol can be used to denote an argument of no fixed type. OPLLINT will not check the type of this argument when the procedure is called. An ellipsis (...) denotes a variable number of arguments to a procedure. OPLLINT will only check the arguments specified before the ellipsis. For a language extension with a variable number of arguments and one argument of no fixed type the file might contain: STRANGE:(string$,notfixed*,number%,...) Calls to this language extension would then be allowed to have 3 or more arguments, and the second argument could be of any type. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 29 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 7 ORDERING PROCEDURES If you are using an Organiser OPLLINT has two features to help you order your procedures on a datapak in the most efficient way. Procedures at the top of the datapak run faster, and thus should be those most frequently used. OPLLINT keeps a count of how many times a procedure is called in a program. This count can be seen as a procedures' popularity. This popularity count does not take account of a call made within a loop: it is just the number of times the procedure call appears in the program text. OPLLINT will produce a list of all the procedures use in the system along with the popularity count for each procedure. This is done by using the -p flag. OPLLINT can also take your original BLD or OLL file and re- order it using the popularity counts. The most popular procedures will go to the top of the BLD file and hence the datapak. Data files such as ODB files will be given an arbitrary popularity count. This value is by default 10, but can be set using the -T flag. With a value of 10 the ODB files will usually be put in the middle of the pak. The best place to put the data files depends on the program and how often the files are used. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 30 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 8 CUSTOMISING OPLLINT As mentioned earlier OPLLINT is actually run from two batch files OL.BAT and OLR.BAT. These batch files simply call the OPLLINT program with the command line they are given, except that they add a -s flag to tell OPLLINT where the standard language extension files are kept. If you require different defaults for your system you can simply add flags to this batch file. The OL environment variable is also useful for setting up a new set of defaults or commonly used flags (for instance a commonly used language extension file). OLR.BAT is exactly the same as OL.BAT except that output is redirected to a file called ERR.OUT (redirection commands are not passed when batch files are called). Note that a maximum of 16 arguments can be given to OL or OLR due to limits in the number of arguments that can be passed to batch files. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 31 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 9 THE PREPROCESSOR All files that OPLLINT reads are passed through a C style preprocessor. The preprocessor provides C style comments using the /* */ characters: PRINT A$ /* this is a comment */ The preprocessor supports all the standard C preprocessor directives like #define, #include etc. For instance you can define symbolic constants which are then replaced in the main text of the program: #define FALSE -1 ... if A = FALSE PRINT "it was false" endif For more information on the preprocessor see the TRAN user guide in the OPL development kit. OPLLINT defines a symbolic constant _OPLLINT when it runs the preprocessor. This allows you to put OPLLINT specific code in your programs: #ifdef _OPLLINT LOADM "one" /* so that OPLLINT can get the names */ LOADM "two" #else LOADM A$ /* the real program */ #endif ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 32 PSION CORPORATE GROUP OPLLINT USER GUIDE ---------------------------------------------------------------------- 10 FEATURES NEW TO V2.00 10.1 CHANGES FROM V1.12 TO V2.00 þ The -x flag has now been replaced by the -txp flag. 10.2 FEATURES ADDED TO OPLLINT V2.00 þ All OPL input files are now preprocessed, including the OLL, BLD and language extension files. þ Multiple OPL and language extension paths are now supported. þ Exact redefinitions of language extensions are now supported. þ Portability warnings are now produced. þ OPLLINT can now determine which target machines a system is compatible with. þ A simple list file input, the OLL file, can be used instead of a BLD file. þ SIBO OPL modules can be automatically located and loaded given the first module. þ OPLLINT now supports MC-OPL and OPL/g in addition to the Organiser OPLs. þ The number of language extension files allowed has been increased to 16. 10.3 FEATURES ADDED TO OPLLINT V2.10 þ OPLLINT will produce a calling structure of a program. 10.4 FEATURES ADDED TO OPLLINT V2.20 þ Support for OPL/w added. ---------------------------------------------------------------------- COPYRIGHT, PSION UK PLC 1990,1991,1992 33